                    Digital Distortion Message Lister
                              Version 1.36
                        Release date: 2013-05-23

                                  by

                             Eric Oulashin
                     Sysop of Digital Distortion BBS
                 BBS internet address: digdist.bbsindex.com
                     Email: eric.oulashin@gmail.com



This file describes the Digital Distortion Message Lister.

Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup
4. Configuration file
5. Drop file for replying to messages with Synchronet message editors
6. DigDistMsgLister class: Properties & methods
7. Revision History


1. Disclaimer
=============
The only guarantee that I can make about Digital Distortion Message Lister
is that it will take up space on your computer.  I have personally only
tested this with the Windows verison of Synchronet 3.15 in Windows 2000,
but I have also seen this script operate on Linux Synchronet systems.  I
I created this script because I felt that it would be useful and am
providing it to the Synchronet BBS community in case other Synchronet
sysops might find it useful.


2. Introduction
===============
The Digital Distortion Message Lister is a door application, written in
JavaScript for Synchronet, that lists the messages in the user's current
sub-board.  It was designed to provide an intuitive user interface, allowing
the user to navigate through the list and select a message to read and
optionally reply to.  This script requires Synchronet version 3.13 or higher.

The following is a list of features:
- Displays a formatted summary list of the messages in the user's current
  sub-board
- Allows the user to read and reply to messages in the sub-board
- Uses the msghdr file(s) in the sbbs/text/menu directory, if it exists, to
  display message header information in a customized format when reading a
  message.  If the msghdr file doesn't exist, the script will use a default
  format for message header information.
- Allows the user to navigate forward and backward through the message list
- Allows the user to navigate to a specific message by number, by pressing G
  (for "Go") at the prompt.
- Provides a lightbar interface (ANSI required), as well as a traditional user
  interface, which prompts for input after each screenful of message listings
- Supports listing messages in forward or reverse order.  Reverse order has the
  effect of ordering the list descending by date & time, with the newest on top.
  When the script starts, the user will be asked if they want to list the messages
  in reverse order.
- Allows the user to delete and edit existing messages that they've written, if the
  sub-board supports those operations.
- The program settings and colors can be changed via a configuration file.  The
  configuration file may be placed in the same directory as the .js script or
  in the sbbs/ctrl directory for a more "standard"-style Synchronet
  installation.
- For developers/programmers: The lister is written as a class.  So if desired,
  message listing can be launched in other JavaScript scripts by creating an
  instance of the DigDistMsgLister class, customizing the colors or other
  properties as desired, and calling the ListMessages method.  For the default
  options, the DigitalDistortionMessageLister.js script is suitable.

If a message has been marked for deletion, it will appear with a blinking red
asterisk (*) after the message number in the message list.

When displaying a message to the user, this script will honor the attribute
code toggles set up under Synchronet's configuration program (SCFG),
under Message Options > Extra Attribute Codes.


3. Installation & Setup
=======================
If you already have the message lister installed and are upgrading from a
previous version, see the file "Upgrading.txt" for details on the changes in
various versions.

Digital Distortion Message Lister is comprised of the following files:
 1. DigitalDistortionMessageLister.js
 2. DD_AttrCodeFunctions.js
 3. DigitalDistortionMessageListerReverse.js
 4. DigitalDistortionListEmail.js
 5. DigitalDistortionMessageLister.cfg
The first script, DigitalDistortionMessageLister.js, is the main script.  It
contains the message lister class and default execution code.  This is the script you
will want to run for normal operation.

The files can be placed together in any directory.  No additional initial
configuration is required, aside from placing the script in your command shell or
other scripts where you want to do a message listing.  However, you can edit
the configuration file to suit your tastes.

The second script, DigitalDistortionMessageListerReverse.js, lists messages in
reverse order, regardless of the message order setting in the configuration file.
In your configuration file, if you choose to keep the default behavior of listing
messages in forward order, you may also want to use the second script so that your
users have the option of listing messages in reverse order.
The second script is not a complete copy of the first; therefore, the first script is
required for the second.  The second script can also be used as an example of how to
customize the message lister class, DigDistMsgLister, for different behaviors.

The third script, DigitalDistortionListEmail.js, can be used to list personal
email.

The scripts can be run from a Baja script or a JavaScript application.  For the following
examples, I'll use DigitalDistortionMessageLister.js.  The following instructions assume
that the scripts and configuration file are placed in the SBBS "exec" directory.

To use the message lister in a Baja script, include the following line to run the
message lister:
   exec "?DigitalDistortionMessageLister.js"

Running the script from JavaScript can be done in several ways:
1) The load() function, as in the following:
   load("DigitalDistortionMessageLister.js");
2) The message lister code is actually contained in a JavaScript class, called DigDistMsgLister.
   If you want to change the colors, user interface used, or other options, you can follow
   these steps:
   1. Create your own JavaScript source file
   2. At the top of your JavaScript source file, include DigitalDistortionMessageLister.js
      using the load() function, and pass false as the second parameter, as in the following
      example:
        load("DigitalDistortionMessageLister.js", false);
      The false will cause the lister not to execute; the script will simply provide the class
      definition for your use. (Note: Using load() this way is a way to pass arguments to a
      JavaScript source file, in the argv array.  In DigitalDistortionMessageLister.js, the
      false is recognized as argv[0].)
   3. Create a DigDistMsgLister instance, set any options you'd like to set, and call
      ListMessages(), passing the sub-board code to list.  Example:
        var msgLister = new DigDistMsgLister();
        msgLister.interfaceStyle = "Lightbar";
        msgLister.ListMessages(user.cursub);
      Note: To change to the traditional user interface (scrolling, prompt the user at the
      end of each page), you can change the interfaceStyle property to "Traditional",
      as follows:
        msgLister.interfaceStyle = "Traditional";
      One of the other properties, displayBoardInfoInHeader, can be changed to toggle
      the display of the message sub-board information in the header above the message
      listing.  It takes a boolean.  Example:
        msgLister.displayBoardInfoInHeader = true;
      Another property, reverseOrder, specifies whether or not to display the messages
      in reverse order (descending by date & time).  It can be either a boolean (true
      or false), or the string "ask" to ask the user whether they want the list
      displayed in reverse.


4. Configuration file
=====================
If you want to change the default beavior and colors, you can edit the
configuration file, which is a plain text file.  The configuration file has two
sections: A behavior section (denoted by [BEHAVIOR]) and a colors section
(denoted by [COLORS]).  For each setting and color, the syntax is in a
setting=value format, where "setting" is the name of the setting or color, and
"value" is the corresponding value for the setting/color.  The colors are
Synchronet color codes.

Also, comments are allowed in the configuration file.  Commented lines begin
with a semicolon (;).

Behavior section
----------------
Setting                               Description
-------                               -----------
interfaceStyle                        String: The user interface to use.  Valid values
                                      are "Traditional" (traditional user interface
                                      with user prompted for input at the end of each
                                      screenful) and "Lightbar" (use the lightbar user
                                      interface).

displayBoardInfoInHeader              true/false: Whether or not to display sub-board
                                      information above the column headers when listing
                                      the message information.  If this is set to true,
                                      2 extra lines on the screen will be used at the top
                                      to display message group and sub-board.

reverseOrder                          true/false: Whether or not to display the list
                                      in reverse order, or the string "ask" to ask the user
                                      whether they want the list displayed in reverse.  If
                                      the list is displayed in reverse, that has the effect
                                      of listing in descending order by  date & time.

promptToContinueListingMessages       true/false: Whether or not to prompt the
                                      user to continue listing messages after
                                      a message is read.

promptConfirmReadMessage              true/false: Whether or not to prompt the
                                      user to read a message when one is
                                      selected.

messageDateDisplayed                  Specifies the message date to display.  Valid values
                                      are imported and written.
                                      imported: Display the message import dates
                                      written: Display the message written dates

msgHdrTextFileName                    The name of the message header text file
                                      (without extension) in the sbbs/text/menu
                                      directory.  The default is msghdr, which
                                      is what Synchronet uses.  The name can be
                                      customized in case you want a different
                                      file specifically for the message lister.
                                      The filename extension .ans or .asc is
                                      chosen automatically depending on whether
                                      the user's terminal supports ANSI and if
                                      the .ans file or .asc file exists.

Colors section
--------------
Color setting                        Description
-------------                        -----------
headerMsgGroupText                   Header line displaying the message group, for the
                                     text Current msg group:
headerMsgGroupName                   Header line displaying the message group, for the
                                     message group

headerSubBoardText                   Header line displaying the message sub-board, for the
                                     text Current msg sub-board:
headerMsgSubBoardName                Header line displaying the message sub-board, for the
                                     message sub-board

listColHeader                        Column names for the list

headerSeparatorLine                  The line separating the column names from the list

msgNum                               Message number (in the list)
from                                 Sender name (in the list)
to                                   Destination name (in the list)
subject                              Message subject (in the list)
date                                 Message date (in the list)
time                                 Message time (in the list)

toUserMsgNum                         Message numer, for messages to the user
toUserFrom                           Sender name, for messages to the user
toUserTo                             Destination name, for messages to the user
toUserSubject                        Message subject, for messages to the user
toUserDate                           Message date, for messages to the user
toUserTime                           Message time, for messages to the user

fromUserMsgNum                       Message numer, for messages from the user
fromUserFrom                         Sender name, for messages from the user
fromUserTo                           Destination name, for messages from the user
fromUserSubject                      Message subject, for messages from the user
fromUserDate                         Message date, for messages from the user
fromUserTime                         Message time, for messages from the user

msgHighlightBkg                      Message highlighting background color (for lightbar mode)

contPromptMain                       For the traditional user interface: The text
                                     displayed in the per-screen user prompt

contPromptHotkeys                    For the traditional user interface: The hotkeys
                                     displayed in the per-screen user prompt

contPromptUserInput                  For the traditional user interface: User input
                                     at screen pauses

msgBody                              The message body, when the user chooses to
                                     read a message

readMsgConfirm                       Text used for asking the user if they really want to
                                     read the message
readMsgConfirmNumber                 For the message number displayed when asking the user
                                     if they really want to read the message

afterReadMsg_ListMorePrompt          Text used for asking the user if they want to continue
                                     listing messages

helpScreen                           For the text used in the help screen


5. Drop file for replying to messages with Synchronet message editors
=====================================================================
When reading a message, the message lister will write a drop file in the node
directory, called DDML_SyncSMBInfo.txt, which contains some information about
the message being read, for use by Synchronet message editors.  This drop file
is provided for Synchronet message editors to get information about the current
message being read if needed.  In Synchronet's JavaScript object model, there
are certain variables that are provided about the current message and sub-board
being read that are normally updated by Synchronet's built-in message read
prompt, but JavaScript scripts cannot modify those values.  Because of that,
the solution was for the message lister to provide the message information in a
drop file in the node directory just before allowing the user to reply to a
message.  When the user is done replying to the message, DDML_SyncSMBInfo.txt
will be deleted.
DDML_SyncSMBInfo.txt contains the following information:
Line 1: The highest message number in the sub-board.  Equivalent to
        bbs.smb_last_msg in Synchronet's JavaScript object model.
Line 2: The total number of messages in the sub-board.  Equivalent to
        bbs.smb_total_msgs in Synchronet's JavaScript object model.
Line 3: The (absolute) message number of the message being read.  Equivalent to
        bbs.msg_number in Synchronet's JavaScript object model and the "header"
        property of a message header.
Line 4: The sub-board code (text).  Equivalent to bbs.smb_sub_code in
        Synchronet's JavaScript object model.

One message editor in particular, SlyEdit, needs to be able to determine which
message is currently being read and replied to so that it can retrieve the
message author's initials for use in quoting the messsage.  Normally, SlyEdit
will get the message information from the aforementioned JavaScript variables
provided by Synchronet, but if DDML_SyncSMBInfo.txt exists, SlyEdit will read
the message information from that file instead.
Note that if you have SlyEdit installed on your BBS, this version of Digital
Distortion Message Lister (1.36) requires version 1.27 or newer of SlyEdit in
order for SlyEdit to properly get the correct message from the message lister.

6. DigDistMsgLister class: Properties & methods
===============================================
The following are the properties and methods of the DigDistMsgLister class, which
can be used in JavaScript scripts:
Property name                         Description
-------------                         -----------
subBoardCode                          String: This is the Synchronet sub-board code; it
                                      specifies which message area to use.  This can
                                      also be "mail" for personal email.

interfaceStyle                        String: The user interface to use.  Valid values
                                      are "Traditional" (traditional user interface
                                      with user prompted for input at the end of each
                                      screenful) and "Lightbar" (use the lightbar user
                                      interface).

reverseOrder                          Boolean: Whether or not to display the list in
                                      reverse order, or the string "ask" to ask the user
                                      whether they want the list displayed in reverse.  If
                                      the list is displayed in reverse, that has the effect
                                      of listing in descending order by  date & time.

displayBoardInfoInHeader              Boolean: Whether or not to display sub-board
                                      information above the column headers when listing
                                      the message information.  If this is set to true,
                                      2 extra lines on the screen will be used at the top
                                      to display message group and sub-board.

promptToContinueListingMessages       Boolean: Whether or not to prompt the user to continue
                                      listing messages after a message is read.

displayMessageDateImported            Boolean: Whether or not to display message import
                                      dates (rather than message written dates).

sMsgInfoFormatStr                     The format string (printf-style) used for displaying
                                      message information lines in the message listing.

sMsgInfoFormatHighlightStr            Same as sMsgInfoFormatStr, but used for highlighting
                                      the line on screen.  The only difference is the colors.

sStartContinuePrompt                  For the traditional user interface: The text used
                                      for prompting the user at the end of the first page.

sContinuePrompt                       For the traditional user interface: The text used
                                      for prompting the user at the end of the page (except
                                      for the first & last pages).

sEndContinuePrompt                    For the traditional user interface: The text used
                                      for prompting the user at the end of the last page.

sOnlyOnePageContinuePrompt            For the traditional user interface: The text used
                                      for prompting the user at the end of the page, when
                                      there is only one page.

sLightbarModeHelpLine                 For the lightbar user interface: The help text that
                                      appears on the bottom of the screen.

colors                                An array, indexed with strings, containing the colors
                                      used for the different parts of the lister.  The
                                      array index is a description of what the color is
                                      used for.  These descriptions are the same as the
                                      color setting names used in the configuration file
                                      (see section 3: Configuration file).

Methods
-------
Method name                           Description
-----------                           -----------
DigDistMsgLister(pSubBoardCode)       This is the constructor for DigDistMsgLister
                                      objects.  pSubBoardCode is optional and specifies
                                      the Synchronet sub-board code, or "mail" for
                                      personal email.  If the sub-board code is not
                                      provided here, it must be specified by setting
                                      the subBoardCode property or provided for
                                      ListMessages().


ListMessages(pSubBoardCode)           Performs the message listing, given a sub-board
                                      code.  pSubBoardCode is optional and specifies
                                      the Synchronet sub-board code, or "mail" for
                                      personal email.  If the sub-board code is not
                                      provided here, it must be specified by setting
                                      the subBoardCode property or provided when
                                      the constructor is called.
                                      This method uses the interface style specified
                                      by the interfaceStyle property.  Note that
                                      the lightbar interface requires an ANSI terminal,
                                      and if the interfaceStyle property is set to
                                      "Lightbar" and the user's terminal doesn't
                                      support ANSI, the lister will fall back to
                                      the traditional user interface style.